1 Introduction

  • You can download the workshop material on github.

  • Don’t hesitate to comment (new issues), or request changes (pull request) on .


 

  • Follow the .html (web browser) and the .Rmd (Rstudio) documents. Try and experiment.

  • ~2 hours: Introduction and practice

  • ~15 minutes: pause

  • ~1 hour: other formats (.docx, .pdf). Workshop here

  • ~15 minutes: shiny. Workshop here

2 Markdown

  • Markdown is a lightweight markup language with plain text formatting syntax (Easy-to-read, easy-to-write plain text format). It is designed so that it can be easily converted to HTML and many other formats (e.g. PDF, MS Word, .docx).

  • Like other markup languages (e.g. HTML and Latex), it is completely independent from R.

  • Typically, file have the extension .md.

  • Look at this example. Examine the html render (github automatically interprets .md files) and raw file.

3 R Markdown

  • An extension of the markdown syntax that enables R code to be embedded and executed.

  • Generate fully reproducible reports in different of static and dynamic output formats.

  • Most of these packages are maintained by the Rstudio team (https://rmarkdown.rstudio.com/, Yihui Xie)

  • Plain text files that typically have the file extension .Rmd.

  • So, how does it work:
    • Write text & code in Rstudio.

    • Knit: The R package rmarkdown feeds the .Rmd file to the R package knitr.

    • knitr executes code and creates a new markdown (.md) document which includes the code and output.

    • Subsequently tranformed into .html/.tex/.docx by pandoc. (Note that .tex files need to be transformed by pdflatex into .pdf files. We’ll come back to that later.)

    • Pandoc is an universal document converter, independent of R.

    • By default, Rstudio comes with rmarkdown, knitr, and pandoc (but not pdflatex).

    • When you click the Knit button (top left), a document will be generated that includes both content as well as the output of R code within the document.

3.1 Exercice 1: Setting up an R markdown file (10 min.)

  • This is easily done through R studio


 

  • file > new file > R markdown > HTML

  • Save it (“myfirstRmarkdown.Rmd”)

  • Knit


 

  • Examine the .html output.

  • Examine at the .Rmd file structure.

4 R markdown syntax

  • Markdown provides an easy way to make standard types of formatted text, like:

    • italics (*text*) or italics (_text_)

    • bold (**bold**)

    • backslash (\) to interpret a special characters as character

    • # and space at the beginning of line for a header level (6 levels, # to ######)

    • bold italic (_**bold italic**_)

    • links ([links](https://www.rmarkdown.rstudio.com))

    • Two spaces for a newline character

    • “ ” character (html Non-Breaking SPace) for extra line spacing can be useful.

    • list (first element using * and space, then idented (tab or 2 spaces) * and space)
      • item 1a
      • item 1b
    • quoted text (`quoted text`)


> Quoted text: 1st way
> more quoted text
> still more quoted text

Quoted text: 1st way
more quoted text
still more quoted text


`Quoted text: 2nd way`
`more quoted text`
`still more quoted text`

Quoted text: 2nd way
more quoted text
still more quoted text


```
text: 3rd way
quoted text
more quoted text
```

Quoted text: 3rd way    
more quoted text         
still more quoted text        

  • Tables

Species | Counts
——— | —–
H. sapiens | 24
M. musculus | 442

Species Counts
H. sapiens 24
M. musculus 442

4.1 Exercice 2 (10 min.)

  • Lets write some text now (add italicized/bold text, some URLs, and an itemized list, have fun!). Convert the document to a webpage.

6 Customizing header

---  
title: "Rmarkdown"  
author: "Sebastien Renaut"  
date: "February 27, 2019"   
output: 
#pdf_document:
 html_document:  
   highlight: tango  
   number_sections: T  
   theme: united 
   toc: yes  
   toc_depth: 3  
---  
  • Note the indentation in the .Rmd document for the output options.
  • Note the # symbol to comment out option.
  • Note that date is population via an R function

6.1 Outputs

See the documentation for more information. But these are some formats of interest:

  • output: html_document

  • output: ioslides_presentation

  • output: pdf_document (This will require that you have a Latex software installed - We’ll get to that later).

  • output: word_document (.docx)

  • interactive shiny apps (We’ll get to that later).

6.2 Customizing header: Table of content

  • toc: yes Generate TOC.

  • toc_depth:3 depth of TOC.

  • number_sections:T Add section numbering to headers. If you do not want a certain heading to be numbered, you can add {-} or {.unnumbered} after the heading, e.g.,

6.3 Customizing header: Theme, highlight & other options

  • theme: specifies the theme to use for the page (“cerulean”, “journal”, “flatly”, “readable”, “spacelab”, “united”, and “cosmo”).

  • highlight: Syntax highlighting style (e.g. “tango”, “pygments”, “kate”, “zenburn”).

  • See this Reference guide for more options.

6.4 Exercice 3 (10 min.)

  • Change theme of your Rmarkdown document
  • Change highlighting
  • Add TOC
  • Try saving it as output: word_document
  • Save, knitr and play with options.

7 Code chunks

  • The real power of R Markdown comes from mixing markdown with chunks of code.

  • A code chunk is intepreted by knitr. It works essentially the same as the R syntax we are familiar with.

  • A main code chunks may look like this:

```{r code chunk example, include = T, message = T, warning=T, echo = T, fig.cap="Figure 1"}  
#Running some R code.
x = rexp(1000)  
min(x)  
max(x)  
plot(x)  
```    
  • On the 1st line, I specify that I will run the R programming language.

  • Then, I give the chunk a UNIQUE name and specify options.

  • Here are common options:
    • include = F: Code and results will NOT appear in the finished file. Code is still interpreted, and the results can be used by other chunks.

    • echo = FALSE prevents code, but not results from appearing in the finished file. This is a useful way to embed figures.

    • message = FALSE prevents messages that are generated by code from appearing in the finished file.

    • warning = FALSE prevents warnings that are generated by code from appearing in the finished file.

    • fig.cap = "..." adds a caption to graphical results.

    • fig.width=..., fig.height=... can also change figure width/heigth.

  • By default R studio creates a Global Options code chunk. Let’s examine this chunk:

```{r setup, include=FALSE}  
knitr::opts_chunk$set(echo = TRUE)  
```  
  • see cheat sheet for more info.

  • Note that you also run inline code using the using the ` ` symbols and specifying the programming language. For example, ` r 10+5 ` would be processes as 15.

7.1 Exercice 4 (10 min.)

  • Add a code chunks that will:
    • load an R package and make a plot
    • load an R package and print some output of a function
  • Run inline code.
  • Can you find options to print code, but not run it?
  • Also, try clicking the green arrow in the .Rmd on the right to execute a code chunk a preview its output.

7.2 More Code chunks

R markdown can read and execute different languages!

## rmarkdown_main.Rmd
## rmarkdown_main.html
## rmarkdown_main.log
## rmarkdown_main.tex
## rmarkdown_word_pdf.Rmd
## rmarkdown_word_pdf.html
## rmarkdown_word_pdf.pdf
## rmarkdown_word_pdf.tex
## rsconnect
## shiny.Rmd
## test.Rmd
## test.html
## ['hello', 'python!']
## Hello perl!

7.3 Math symbols

Mathematical material is set off by the use of single dollar-sign characters (similar as in the LaTeX typesetting language).

  • So to write \(E = mc^{2}\), you’d write: $E = mc^{2}$

  • \(\sum_{i=1}^n ASV\)

  • \(F_{(1,69)}\) = 1.27, p-value=0.26

  • \(A = \pi*r^{2}\)

  • \(\sqrt{b^2 - 4ac}\)

  • If you wish to use a dollar sign, you need to preface it with a back-slash \(E = mc^{2}\) versus $E = mc^{2}$

  • The use of double dollars quote allows for displayed formulas (centered). \[\sqrt{b^2 - 4ac}\]

  • See more example equations from this McGill math Rmarkdown tutorial.

8 Include pictures & figures.

  • There are several ways to include figures.

  • Can be included from an URL directly uploaded from the web:
    ![optional caption here](https://static.independent.co.uk/s3fs-public/styles/article_large/public/thumbnails/image/2017/09/12/11/naturo-monkey-selfie.jpg){width=250px}

Optional caption here
 
 
 

  • If this figure is small, it can be added to the text directly: eg.: Today, we are using to generate webpages with images…

  • This is a graph previously saved in the figures directory
    ![](../figures/DEG_heatmap.png){width=250px}
     

  • In all these cases, graphs are rendered with pandoc and not knitr, so pandoc options need to be specified, not R graphics options:
    • It’s simple, but options are tricky.

    • You may need to play with spacing, figure size, and figure position.

    • Options are specified directly after the URL or link (eg. {width=250px} or {width=50%}).

  • Images can also be interpreted by knitr as below:

```{r graphic_example, out.width = "20%", fig.cap = "An orange man", echo = F,fig.align = "center"}  
knitr::include_graphics("../figures/orange.jpeg")  
```
An orange man

An orange man

  • Graphs can also be generated directly by R code, specified in a code chunk (R options specified in the code chunk) and interpreted by knitr as we did previously.
```{r another example, echo = T, message = F}
library(ggplot2)
mtcars_ggplot = ggplot(mtcars, aes(x=wt, y=mpg)) + 
geom_point() + geom_smooth()
mtcars_ggplot
```

9 Including Tables

  • By default, R Markdown displays data frames and matrices as they would be in the R terminal (in a monospaced font).

  • You can use the knitr::kable function for additional formatting, as in the .Rmd file below.

##                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
## Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
## Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
## Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
## Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
## Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
## Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1
A motorcars table
mpg cyl disp hp drat wt qsec vs am gear carb
Mazda RX4 21.0 6 160 110 3.9 2.6 16.5 0 1 4 4
Mazda RX4 Wag 21.0 6 160 110 3.9 2.9 17.0 0 1 4 4
Datsun 710 22.8 4 108 93 3.8 2.3 18.6 1 1 4 1
Hornet 4 Drive 21.4 6 258 110 3.1 3.2 19.4 1 0 3 1
Hornet Sportabout 18.7 8 360 175 3.1 3.4 17.0 0 0 3 2
Valiant 18.1 6 225 105 2.8 3.5 20.2 1 0 3 1

9.1 Exercice 5 (10 min.)

  • Find a picture on the web.

  • Add it to document using either knitr or pandoc.

  • Add a table using knitr.

10 Citations, footnotes, bibliography

  • Footnotes are easy when you have a few references. Use [^1] and add reference at the end using same format.1

  • Otherwise, you may specify a bibliography and citation style in the header.

---  
csl: csl/peerj.csl  
bibliography: biblio/test_library.bib  
---
  • The Citation Style Language (.csl) file specifies the reference format.

  • It is an open XML-based language to describe the formatting of citations and bibliographies. Reference management programs using .csl include Zotero, Mendeley and Papers.

  • Most journals should have a .csl file be on this github repo. But you could create your own.

  • A .bib file contains the bibliographic information of your document.

  • Here, I created a a .bib file in the reference management software Papers3.

  • But now, I often copy .bib reference directly from google scholar.

10.1 Citations: examples

  • Example: The bioinformatics program BLAST (Altschul et al., 1997) has been cited nearly 70,000 times!

  • These are three random references (eg. Thibert-Plante & Hendry, 2010; Wagner et al., 2012; Yoshida et al., 2014).

  • Citations go inside square brackets [ ] and are separated by semicolons (;).

  • Each citation must have a unique key, composed of ‘@’ + the citation identifier from the .bib database.

  • A minus sign (-) before the @ will suppress mention of the author in the citation. This can be useful when the author is already mentioned in the text. For example, Stephen Altschul and a bunch of other people (1997) have been cited 70,000 times.

10.2 Exercice 6 (10 min.)

  • Create a library (.bib file) with the references for your five favorite scientific papers.

  • Find and use another Citation Style Language (e.g. Nature, PLOS ONE, Indian Journal Of Dermatology, etc.).

11 Cheatsheets and help

12 References

(Note that references below are generated automatically, except for the footnote.)

Altschul SF., Madden TL., Schäffer AA., Zhang J., Zhang Z., Miller W., Lipman DJ. 1997. Gapped blast and psi-blast: A new generation of protein database search programs. Nucleic acids research 25:3389–3402.

Thibert-Plante X., Hendry A. 2010. The consequences of phenotypic plasticity for ecological speciation. Journal Of Evolutionary Biology:1–17.

Wagner CE., Keller I., Wittwer S., Selz OM., Mwaiko S., Greuter L., Sivasundar A., Seehausen O. 2012. Genome-wide RAD sequence data provide unprecedented resolution of species boundaries and relationships in the Lake Victoria cichlid adaptive radiation. 22:787–798.

Yoshida K., Makino T., Yamaguchi K., Shigenobu S., Hasebe M., Kawata M., Kume M., Mori S., Peichel CL., Toyoda A., Fujiyama A., Kitano J. 2014. Sex Chromosome Turnover Contributes to Genomic Divergence between Incipient Stickleback Species. PLoS Genetics 10:e1004223.


  1. Renaut 2019. R markdown footnote. Number 1. pp1-2